<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>diagrams &mdash; The Logtalk Handbook v3.93.0-b01 documentation</title>
      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d75fae25" />
      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094" />
      <link rel="stylesheet" type="text/css" href="../_static/css/custom.css?v=396eccfe" />

  
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
        <script src="../_static/jquery.js?v=5d32c60e"></script>
        <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
        <script src="../_static/documentation_options.js?v=c8100655"></script>
        <script src="../_static/doctools.js?v=9a2dae69"></script>
        <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/js/theme.js"></script>
    <!-- begin favicon -->
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
    <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />
    <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />
    <link rel="manifest" href="/site.webmanifest" />
    <link rel="mask-icon" href="/safari-pinned-tab.svg" color="#5bbad5" />
    <meta name="msapplication-TileColor" content="#355b95" />
    <meta name="theme-color" content="#ffffff" />
    <!-- end favicon -->
    
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="doclet" href="doclet.html" />
    <link rel="prev" title="debugger" href="debugger.html" />
   
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="../index.html" class="icon icon-home">
            The Logtalk Handbook
              <img src="../_static/logtalk.gif" class="logo" alt="Logo"/>
          </a>
              <div class="version">
                3.93.0
              </div>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
    
              <p class="caption" role="heading"><span class="caption-text">Contents</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../userman/index.html">User Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../refman/index.html">Reference Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../faq/index.html">FAQ</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Developer Tools</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="overview.html">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="asdf.html"><code class="docutils literal notranslate"><span class="pre">asdf</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="assertions.html"><code class="docutils literal notranslate"><span class="pre">assertions</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="code_metrics.html"><code class="docutils literal notranslate"><span class="pre">code_metrics</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="dead_code_scanner.html"><code class="docutils literal notranslate"><span class="pre">dead_code_scanner</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="debug_messages.html"><code class="docutils literal notranslate"><span class="pre">debug_messages</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="debugger.html"><code class="docutils literal notranslate"><span class="pre">debugger</span></code></a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#"><code class="docutils literal notranslate"><span class="pre">diagrams</span></code></a><ul>
<li class="toctree-l3"><a class="reference internal" href="#requirements">Requirements</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#macos-macports">macOS - MacPorts</a></li>
<li class="toctree-l4"><a class="reference internal" href="#macos-homebrew">macOS - Homebrew</a></li>
<li class="toctree-l4"><a class="reference internal" href="#windows-chocolatey">Windows - Chocolatey</a></li>
<li class="toctree-l4"><a class="reference internal" href="#installers">Installers</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#api-documentation">API documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="#loading">Loading</a></li>
<li class="toctree-l3"><a class="reference internal" href="#testing">Testing</a></li>
<li class="toctree-l3"><a class="reference internal" href="#supported-diagrams">Supported diagrams</a></li>
<li class="toctree-l3"><a class="reference internal" href="#graph-elements">Graph elements</a></li>
<li class="toctree-l3"><a class="reference internal" href="#supported-graph-languages">Supported graph languages</a></li>
<li class="toctree-l3"><a class="reference internal" href="#customization">Customization</a></li>
<li class="toctree-l3"><a class="reference internal" href="#linking-diagrams">Linking diagrams</a></li>
<li class="toctree-l3"><a class="reference internal" href="#creating-diagrams-for-prolog-module-applications">Creating diagrams for Prolog module applications</a></li>
<li class="toctree-l3"><a class="reference internal" href="#creating-diagrams-for-plain-prolog-files">Creating diagrams for plain Prolog files</a></li>
<li class="toctree-l3"><a class="reference internal" href="#other-notes">Other notes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="doclet.html"><code class="docutils literal notranslate"><span class="pre">doclet</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="help.html"><code class="docutils literal notranslate"><span class="pre">help</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="issue_creator.html"><code class="docutils literal notranslate"><span class="pre">issue_creator</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="lgtdoc.html"><code class="docutils literal notranslate"><span class="pre">lgtdoc</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="lgtunit.html"><code class="docutils literal notranslate"><span class="pre">lgtunit</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="linter.html"><code class="docutils literal notranslate"><span class="pre">linter</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="make.html"><code class="docutils literal notranslate"><span class="pre">make</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="packs.html"><code class="docutils literal notranslate"><span class="pre">packs</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="ports_profiler.html"><code class="docutils literal notranslate"><span class="pre">ports_profiler</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="profiler.html"><code class="docutils literal notranslate"><span class="pre">profiler</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="tutor.html"><code class="docutils literal notranslate"><span class="pre">tutor</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="wrapper.html"><code class="docutils literal notranslate"><span class="pre">wrapper</span></code></a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../libraries/index.html">Libraries</a></li>
<li class="toctree-l1"><a class="reference internal" href="../ports/index.html">Ports</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributions/index.html">Contributions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../bibliography.html">Bibliography</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html">Index</a></li>
</ul>

    <p class="caption"><span class="caption-text">External Contents</span></p>
    <ul>
    <li class="toctree-l1"><a class="reference internal" href="../../apis/index.html">APIs</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://logtalk.org">Logtalk website</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://github.com/LogtalkDotOrg/logtalk3">GitHub repo</a></li>
    </ul>
  
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">The Logtalk Handbook</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="index.html">Developer Tools</a></li>
      <li class="breadcrumb-item active"><code class="docutils literal notranslate"><span class="pre">diagrams</span></code></li>
      <li class="wy-breadcrumbs-aside">
              <a href="https://github.com/LogtalkDotOrg/logtalk3/blob/master/docs/handbook/sources/devtools/diagrams.rst" class="fa fa-github"> Edit on GitHub</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="diagrams">
<span id="library-diagrams"></span><h1><code class="docutils literal notranslate"><span class="pre">diagrams</span></code><a class="headerlink" href="#diagrams" title="Link to this heading"></a></h1>
<p>This tool generates <em>library</em>, <em>directory</em>, <em>file</em>, <em>entity</em>, and
<em>predicate</em> diagrams for source files and for libraries of source files
using the Logtalk reflection API to collect the relevant information and
a graph language for representing the diagrams. Limited support is also
available for generating diagrams for Prolog module applications. It’s
also possible in general to generate predicate cross-referencing
diagrams for plain Prolog files.</p>
<p>Linking <em>library diagrams</em> to <em>entity diagrams</em> to <em>predicate
cross-referencing diagrams</em> and linking <em>directory diagrams</em> to <em>file
diagrams</em> is also supported when using SVG output. This feature allows
using diagrams for understanding the architecture of applications by
navigating complex code and zooming into details. SVG output can also
easily link to both source code repositories and API documentation. This
allows diagrams to be used for source code navigation.</p>
<p>Diagrams can also be used to uncover code issues. For example, comparing
<em>loading diagrams</em> with <em>dependency diagrams</em> can reveal implicit
dependencies. Loading diagrams can reveal circular dependencies that may
warrant code refactoring. Entity diagrams can provide a good overview of
code coupling. Predicate cross-referencing diagrams can be used to
visually access entity code complexity, complementing the
<code class="docutils literal notranslate"><span class="pre">code_metrics</span></code> tool.</p>
<p>All diagrams support a comprehensive set of options, discussed below, to
customize the final contents and appearance.</p>
<p>Diagram generation can be easily automated using the <code class="docutils literal notranslate"><span class="pre">doclet</span></code> tool and
the <code class="docutils literal notranslate"><span class="pre">logtalk_doclet</span></code> scripts. See the <code class="docutils literal notranslate"><span class="pre">doclet</span></code> tool examples and
documentation for details. See also the <code class="docutils literal notranslate"><span class="pre">diagrams</span></code> tool own
<code class="docutils literal notranslate"><span class="pre">lgt2svg</span></code> Bash and PowerShell scripts.</p>
<section id="requirements">
<h2>Requirements<a class="headerlink" href="#requirements" title="Link to this heading"></a></h2>
<p>Recent versions of d2 (0.6.9 or later) or Graphviz are required for
generating diagrams in the final formats:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://d2lang.com">https://d2lang.com</a></p></li>
<li><p><a class="reference external" href="https://www.graphviz.org/">https://www.graphviz.org/</a></p></li>
</ul>
<p>These can be installed using their own installers or using
operating-system package managers:</p>
<section id="macos-macports">
<h3>macOS - MacPorts<a class="headerlink" href="#macos-macports" title="Link to this heading"></a></h3>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="err">$</span> sudo port install d2 graphviz
</pre></div>
</div>
</section>
<section id="macos-homebrew">
<h3>macOS - Homebrew<a class="headerlink" href="#macos-homebrew" title="Link to this heading"></a></h3>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="err">$</span> brew install d2 graphviz
</pre></div>
</div>
</section>
<section id="windows-chocolatey">
<h3>Windows - Chocolatey<a class="headerlink" href="#windows-chocolatey" title="Link to this heading"></a></h3>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="o">&gt;</span> choco install d2 graphviz
</pre></div>
</div>
</section>
<section id="installers">
<h3>Installers<a class="headerlink" href="#installers" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><a class="reference external" href="https://d2lang.com/tour/install">https://d2lang.com/tour/install</a></p></li>
<li><p><a class="reference external" href="https://www.graphviz.org/download/">https://www.graphviz.org/download/</a></p></li>
</ul>
</section>
</section>
<section id="api-documentation">
<h2>API documentation<a class="headerlink" href="#api-documentation" title="Link to this heading"></a></h2>
<p>This tool API documentation is available at:</p>
<p><a class="reference external" href="../../apis/library_index.html#diagrams">../../apis/library_index.html#diagrams</a></p>
<p>For sample queries, please see the <code class="docutils literal notranslate"><span class="pre">SCRIPT.txt</span></code> file in the tool
directory.</p>
</section>
<section id="loading">
<h2>Loading<a class="headerlink" href="#loading" title="Link to this heading"></a></h2>
<p>This tool can be loaded using the query:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>| <span class="o">?-</span> <span class="k">logtalk_load</span>(diagrams(loader)).
</pre></div>
</div>
</section>
<section id="testing">
<h2>Testing<a class="headerlink" href="#testing" title="Link to this heading"></a></h2>
<p>To test this tool, load the <code class="docutils literal notranslate"><span class="pre">tester.lgt</span></code> file:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>| <span class="o">?-</span> <span class="k">logtalk_load</span>(diagrams(tester)).
</pre></div>
</div>
</section>
<section id="supported-diagrams">
<h2>Supported diagrams<a class="headerlink" href="#supported-diagrams" title="Link to this heading"></a></h2>
<p>The following entity diagrams are supported:</p>
<ul class="simple">
<li><p><em>entity diagrams</em> showing entity public interfaces, entity inheritance
relations, and entity predicate cross-reference relations</p></li>
<li><p><em>predicate cross-reference diagrams</em> (between entities or within an
entity)</p></li>
<li><p><em>inheritance diagrams</em> showing entity inheritance relations</p></li>
<li><p><em>uses diagrams</em> showing which entities use resources from other
entities</p></li>
</ul>
<p>The following library diagrams are supported:</p>
<ul class="simple">
<li><p><em>library loading diagrams</em> showing which libraries load other
libraries</p></li>
<li><p><em>library dependency diagrams</em> showing which libraries contain entities
with references to entities defined in other libraries</p></li>
</ul>
<p>The following file diagrams are supported:</p>
<ul class="simple">
<li><p><em>file loading diagrams</em> showing which files load or include other
files</p></li>
<li><p><em>file dependency diagrams</em> showing which files contain entities with
references to entities defined in other files</p></li>
</ul>
<p>File dependency diagrams are specially useful in revealing dependencies
that are not represented in file loading diagrams due to files being
loaded indirectly by files external to the libraries being documented.</p>
<p>The following directory diagrams are supported:</p>
<ul class="simple">
<li><p><em>directory loading diagrams</em> showing which directories contain files
that load files from other directories</p></li>
<li><p><em>directory dependency diagrams</em> showing which directories contain
entities with references to entities defined in other directories</p></li>
</ul>
<p>Comparing directory (or file) loading diagrams with directory (or file)
dependency diagrams allows comparing what is explicitly loaded with the
actual directory (or file) dependencies, which are inferred from the
source code.</p>
<p>Library and directory dependency diagrams are specially useful for large
applications where file diagrams would be too large and complex to be
useful, notably when combined with the <em>zoom</em> option to link to,
respectively, entity and file diagrams.</p>
<p>A utility object, <code class="docutils literal notranslate"><span class="pre">diagrams</span></code>, is provided for generating all supported
diagrams in one step. This object provides an interface common to all
diagrams, but note that some predicates that generate diagrams only make
sense for some types of diagrams. For best results and fine-grained
customization of each diagram, the individual diagram objects should be
used with the intended set of options.</p>
</section>
<section id="graph-elements">
<h2>Graph elements<a class="headerlink" href="#graph-elements" title="Link to this heading"></a></h2>
<p>Limitations in both the graph languages and UML force the invention of a
modeling language that can represent all kinds of Logtalk entities and
entity relations. Currently we use the following Graphviz node shapes
(libraries, entities, predicates, and files) and arrowheads (entity,
predicate, and file relations):</p>
<ul>
<li><div class="line-block">
<div class="line">libraries</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">tab</span></code> (lightsalmon)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">library loading and dependency relations</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">normal</span></code> (arrow ending with a black triangle)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">objects (classes, instances, and prototypes)</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">box</span></code> (rectangle, yellow for instances/classes and beige for
prototypes)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">protocols</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">note</span></code> (aqua marine rectangle with folded right-upper corners)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">categories</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">component</span></code> (light cyan rectangle with two small rectangles
intercepting the left side)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">modules</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">box</span></code> (plum rectangle with small tab at top)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">public predicates</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">box</span></code> (springgreen)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">public, multifile, predicates</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">box</span></code> (skyblue)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">protected predicates</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">box</span></code> (yellow)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">private predicates</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">box</span></code> (indianred)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">external predicates</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">box</span></code> (beige)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">exported module predicates</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">box</span></code> (springgreen)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">directories</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">tab</span></code> (lightsalmon)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">directory loading and dependency relations</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">normal</span></code> (arrow ending with a black triangle)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">files</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">box</span></code> (pale turquoise rectangle)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">file loading and dependency relations</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">normal</span></code> (arrow ending with a black triangle)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">specialization relation</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">onormal</span></code> (arrow ending with a white triangle)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">instantiation relation</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">normal</span></code> (arrow ending with a black triangle)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">extends relation</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">vee</span></code> (arrow ending with a “v”)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">implements relation</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">dot</span></code> (arrow ending with a black circle)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">imports relation</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">box</span></code> (arrow ending with a black square)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">complements relation</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">obox</span></code> (arrow ending with a white square)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">uses and use module relations</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">rdiamond</span></code> (arrow ending with a black half diamond)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">predicate calls</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">normal</span></code> (arrow ending with a black triangle)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">dynamic predicate updates</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">diamond</span></code> (arrow ending with a black diamond)</div>
</div>
</li>
</ul>
<p>When using the d2 graph language, we use similar node shapes and
arrowheads when available. As d2 evolves, we hope that these graph
elements will converge further.</p>
<p>The library, directory, file, entity, and predicate nodes that are not
part of the predicates, entities, files, or libraries for which we are
generating a diagram use a dashed border, a darker color, and are
described as external.</p>
<p>Note that all the elements above can have captions. See below the
diagrams <code class="docutils literal notranslate"><span class="pre">node_type_captions/1</span></code> and <code class="docutils literal notranslate"><span class="pre">relation_labels/1</span></code> output
options.</p>
</section>
<section id="supported-graph-languages">
<h2>Supported graph languages<a class="headerlink" href="#supported-graph-languages" title="Link to this heading"></a></h2>
<p>Currently, both DOT and d2 graph languages support all the features of
the <code class="docutils literal notranslate"><span class="pre">diagrams</span></code> tool. There’s also preliminary support for Mermaid (not
loaded by default, as its current version lacks several required
features for parity with d2 and Graphviz).</p>
<p>The diagrams <code class="docutils literal notranslate"><span class="pre">.d2</span></code> and <code class="docutils literal notranslate"><span class="pre">.dot</span></code> files are created in the current
directory by default. These files can be easily converted into a
printable format such as SVG, PDF, or Postscript. Sample helper scripts
are provided for converting a directory of <code class="docutils literal notranslate"><span class="pre">.d2</span></code> or <code class="docutils literal notranslate"><span class="pre">.dot</span></code> files to
<code class="docutils literal notranslate"><span class="pre">.svg</span></code> files:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">lgt2svg.sh</span></code> for POSIX systems</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">lgt2svg.ps1</span></code> for Windows systems</p></li>
</ul>
<p>The scripts assume that the d2 and Graphviz command-line executables are
available from the system path. For Graphviz, the default is the <code class="docutils literal notranslate"><span class="pre">dot</span></code>
executable, but the scripts accept a command-line option to select in
alternative the <code class="docutils literal notranslate"><span class="pre">circo</span></code>, <code class="docutils literal notranslate"><span class="pre">fdp</span></code>, or <code class="docutils literal notranslate"><span class="pre">neato</span></code> executables). For d2,
the default layout engine is <code class="docutils literal notranslate"><span class="pre">elk</span></code>, but the scripts accept a
command-line option to select in alternative the <code class="docutils literal notranslate"><span class="pre">dagre</span></code> or <code class="docutils literal notranslate"><span class="pre">tala</span></code>
layout engines.</p>
<p>The recommended output format is SVG, as it supports tooltips and URL
links, which can be used for showing, e.g., entity types, relation
types, file paths, and for navigating to files and directories of files
(libraries) or to API documentation. See the relevant diagram options
below in order to take advantage of these features (see the discussion
below on “linking diagrams”).</p>
<p>To convert to formats other than SVG, you will need to use the d2 and
Graphviz executables directly. For example, using the Graphviz <code class="docutils literal notranslate"><span class="pre">dot</span></code>
executable, we can generate a PDF with the command:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>dot <span class="o">-</span><span class="nv">Tpdf</span> diagram.dot <span class="o">&gt;</span> diagram.pdf
</pre></div>
</div>
<p>This usually works fine for entity and predicate call cross-referencing
diagrams. For directory and file diagrams, the <code class="docutils literal notranslate"><span class="pre">fdp</span></code> and <code class="docutils literal notranslate"><span class="pre">circo</span></code>
command-line executables may produce better results. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>fdp <span class="o">-</span><span class="nv">Tsvg</span> diagram.dot <span class="o">&gt;</span> diagram.svg
circo <span class="o">-</span><span class="nv">Tsvg</span> diagram.dot <span class="o">&gt;</span> diagram.svg
</pre></div>
</div>
<p>It’s also worth experimenting with different layouts to find the one
that produces the best results (see the <code class="docutils literal notranslate"><span class="pre">layout/1</span></code> option described
below).</p>
<p>When generating diagrams for multiple libraries or directories, it’s
possible to split a diagram with several disconnected library or
directory graphs using the <code class="docutils literal notranslate"><span class="pre">ccomps</span></code> command-line executable. For
example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>ccomps <span class="o">-</span>x <span class="o">-</span>o subdiagram.dot diagram.dot
</pre></div>
</div>
<p>For more information on the DOT language and related tools, see:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>http<span class="o">://</span>www.graphviz.org<span class="o">/</span>
</pre></div>
</div>
<p>When using Windows, there are known issues with some Prolog compilers
due to the internal representation of paths. If you encounter problems
with a specific backend Prolog compiler, try, if possible, to use
another supported backend Prolog compiler when generating diagrams.</p>
<p>For printing large diagrams, you will need to either use a tool to slice
the diagram into page-sized pieces or, preferably, use software capable
of tiled printing (e.g., Adobe Reader). You can also hand-edit the
generated <code class="docutils literal notranslate"><span class="pre">.dot</span></code> files and play with settings such as aspect ratio for
fine-tuning the diagrams layout.</p>
</section>
<section id="customization">
<h2>Customization<a class="headerlink" href="#customization" title="Link to this heading"></a></h2>
<p>A set of options is available to specify the details to include in the
generated diagrams. For entity diagrams, the options are:</p>
<ul>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">layout(Layout)</span></code></div>
<div class="line">diagram layout (one of the atoms
<code class="docutils literal notranslate"><span class="pre">{top_to_bottom,bottom_to_top,left_to_right,right_to_left}</span></code>;
default is <code class="docutils literal notranslate"><span class="pre">bottom_to_top</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">title(Title)</span></code></div>
<div class="line">diagram title (an atom; default is <code class="docutils literal notranslate"><span class="pre">''</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">date(Boolean)</span></code></div>
<div class="line">print current date and time (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is
<code class="docutils literal notranslate"><span class="pre">true</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">versions(Boolean)</span></code></div>
<div class="line">print Logtalk and backend version data (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>;
default is <code class="docutils literal notranslate"><span class="pre">false</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">interface(Boolean)</span></code></div>
<div class="line">print public predicates (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is <code class="docutils literal notranslate"><span class="pre">true</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">file_labels(Boolean)</span></code></div>
<div class="line">print file labels (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is <code class="docutils literal notranslate"><span class="pre">true</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">file_extensions(Boolean)</span></code></div>
<div class="line">print file name extensions (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is
<code class="docutils literal notranslate"><span class="pre">true</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">relation_labels(Boolean)</span></code></div>
<div class="line">print entity relation labels (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is
<code class="docutils literal notranslate"><span class="pre">true</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">externals(Boolean)</span></code></div>
<div class="line">print external nodes (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is <code class="docutils literal notranslate"><span class="pre">true</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">node_type_captions(Boolean)</span></code></div>
<div class="line">print node type captions (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is
<code class="docutils literal notranslate"><span class="pre">true</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">inheritance_relations(Boolean)</span></code></div>
<div class="line">print inheritance relations (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is
<code class="docutils literal notranslate"><span class="pre">true</span></code> for entity inheritance diagrams and <code class="docutils literal notranslate"><span class="pre">false</span></code> for other
entity diagrams)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">provide_relations(Boolean)</span></code></div>
<div class="line">print provide relations (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is
<code class="docutils literal notranslate"><span class="pre">false</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">xref_relations(Boolean)</span></code></div>
<div class="line">print predicate call cross-reference relations (<code class="docutils literal notranslate"><span class="pre">true</span></code> or
<code class="docutils literal notranslate"><span class="pre">false</span></code>; default depends on the specific diagram)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">xref_calls(Boolean)</span></code></div>
<div class="line">print predicate cross-reference calls (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>;
default depends on the specific diagram)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">output_directory(Directory)</span></code></div>
<div class="line">directory for the <code class="docutils literal notranslate"><span class="pre">.d2</span></code> and <code class="docutils literal notranslate"><span class="pre">.dot</span></code> files (an atom; default is
<code class="docutils literal notranslate"><span class="pre">'./dot_dias'</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">exclude_directories(Directories)</span></code></div>
<div class="line">list of directories to exclude except as external nodes (default is
<code class="docutils literal notranslate"><span class="pre">[]</span></code>); all sub-directories of the excluded directories are also
excluded; directories may be listed by full or relative path</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">exclude_files(Files)</span></code></div>
<div class="line">list of source files to exclude except as external nodes (default is
<code class="docutils literal notranslate"><span class="pre">[]</span></code>); files may be listed by full path or basename, with or
without extension</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">exclude_libraries(Libraries)</span></code></div>
<div class="line">list of libraries to exclude except as external nodes (default is
<code class="docutils literal notranslate"><span class="pre">[startup,</span> <span class="pre">scratch_directory]</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">exclude_entities(Entities)</span></code></div>
<div class="line">list of entities to exclude except as external nodes (default is
<code class="docutils literal notranslate"><span class="pre">[]</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">path_url_prefixes(PathPrefix,</span> <span class="pre">CodeURLPrefix,</span> <span class="pre">DocURLPrefix)</span></code></div>
<div class="line">code and documenting URL prefixes for a path prefix used when
generating cluster, library, directory, file, and entity links
(atoms; no default; can be specified multiple times)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">url_prefixes(CodeURLPrefix,</span> <span class="pre">DocURLPrefix)</span></code></div>
<div class="line">default URL code and documenting URL prefixes used when generating
cluster, library, file, and entity links (atoms; no default)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">entity_url_suffix_target(Suffix,</span> <span class="pre">Target)</span></code></div>
<div class="line">extension for entity documenting URLs (an atom; default is
<code class="docutils literal notranslate"><span class="pre">'.html'</span></code>) and target separating symbols (an atom; default is
<code class="docutils literal notranslate"><span class="pre">'#'</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">omit_path_prefixes(Prefixes)</span></code></div>
<div class="line">omit common path prefixes when printing directory paths and when
constructing URLs (a list of atoms; default is a list with the user
home directory)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">zoom(Boolean)</span></code></div>
<div class="line">generate sub-diagrams and add links and zoom icons to library and
entity nodes (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is <code class="docutils literal notranslate"><span class="pre">false</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">zoom_url_suffix(Suffix)</span></code></div>
<div class="line">extension for linked diagrams (an atom; default is <code class="docutils literal notranslate"><span class="pre">'.svg'</span></code>)</div>
</div>
</li>
</ul>
<p>In the particular case of cross-referencing diagrams, there are also the
options:</p>
<ul>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">recursive_relations(Boolean)</span></code></div>
<div class="line">print recursive predicate relations (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default
is <code class="docutils literal notranslate"><span class="pre">false</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">url_line_references(Host)</span></code></div>
<div class="line">syntax for the URL source file line part (an atom; possible values
are <code class="docutils literal notranslate"><span class="pre">{github,gitlab,bitbucket}</span></code>; default is <code class="docutils literal notranslate"><span class="pre">github</span></code>); when
using this option, the <code class="docutils literal notranslate"><span class="pre">CodeURLPrefix</span></code> should be a permanent link
(i.e., it should include the commit SHA1)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">predicate_url_target_format(Generator)</span></code></div>
<div class="line">documentation final format generator (an atom; default is
<code class="docutils literal notranslate"><span class="pre">sphinx</span></code>)</div>
</div>
</li>
</ul>
<p>For directory and file diagrams, the options are:</p>
<ul>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">layout(Layout)</span></code></div>
<div class="line">diagram layout (one of the atoms
<code class="docutils literal notranslate"><span class="pre">{top_to_bottom,bottom_to_top,left_to_right,right_to_left}</span></code>;
default is <code class="docutils literal notranslate"><span class="pre">top_to_bottom</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">title(Title)</span></code></div>
<div class="line">diagram title (an atom; default is <code class="docutils literal notranslate"><span class="pre">''</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">date(Boolean)</span></code></div>
<div class="line">print current date and time (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is
<code class="docutils literal notranslate"><span class="pre">true</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">versions(Boolean)</span></code></div>
<div class="line">print Logtalk and backend version data (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>;
default is <code class="docutils literal notranslate"><span class="pre">false</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">directory_paths(Boolean)</span></code></div>
<div class="line">print file directory paths (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is
<code class="docutils literal notranslate"><span class="pre">false</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">file_extensions(Boolean)</span></code></div>
<div class="line">print file name extensions (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is
<code class="docutils literal notranslate"><span class="pre">true</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">path_url_prefixes(PathPrefix,</span> <span class="pre">CodeURLPrefix,</span> <span class="pre">DocURLPrefix)</span></code></div>
<div class="line">code and documenting URL prefixes for a path prefix used when
generating cluster, directory, file, and entity links (atoms; no
default; can be specified multiple times)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">url_prefixes(CodeURLPrefix,</span> <span class="pre">DocURLPrefix)</span></code></div>
<div class="line">default URL code and documenting URL prefixes used when generating
cluster, library, file, and entity links (atoms; no default)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">omit_path_prefixes(Prefixes)</span></code></div>
<div class="line">omit common path prefixes when printing directory paths and when
constructing URLs (a list of atoms; default is a list with the user
home directory)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">relation_labels(Boolean)</span></code></div>
<div class="line">print entity relation labels (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is
<code class="docutils literal notranslate"><span class="pre">false</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">externals(Boolean)</span></code></div>
<div class="line">print external nodes (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is <code class="docutils literal notranslate"><span class="pre">true</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">node_type_captions(Boolean)</span></code></div>
<div class="line">print node type captions (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is
<code class="docutils literal notranslate"><span class="pre">false</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">output_directory(Directory)</span></code></div>
<div class="line">directory for the <code class="docutils literal notranslate"><span class="pre">.d2</span></code> and <code class="docutils literal notranslate"><span class="pre">.dot</span></code> files (an atom; default is
<code class="docutils literal notranslate"><span class="pre">'./dot_dias'</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">exclude_directories(Directories)</span></code></div>
<div class="line">list of directories to exclude except as external nodes (default is
<code class="docutils literal notranslate"><span class="pre">[]</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">exclude_files(Files)</span></code></div>
<div class="line">list of source files to exclude except as external nodes (default is
<code class="docutils literal notranslate"><span class="pre">[]</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">zoom(Boolean)</span></code></div>
<div class="line">generate sub-diagrams and add links and zoom icons to library and
entity nodes (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is <code class="docutils literal notranslate"><span class="pre">false</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">zoom_url_suffix(Suffix)</span></code></div>
<div class="line">extension for linked diagrams (an atom; default is <code class="docutils literal notranslate"><span class="pre">'.svg'</span></code>)</div>
</div>
</li>
</ul>
<p>For library diagrams, the options are:</p>
<ul>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">layout(Layout)</span></code></div>
<div class="line">diagram layout (one of the atoms
<code class="docutils literal notranslate"><span class="pre">{top_to_bottom,bottom_to_top,left_to_right,right_to_left}</span></code>;
default is <code class="docutils literal notranslate"><span class="pre">top_to_bottom</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">title(Title)</span></code></div>
<div class="line">diagram title (an atom; default is <code class="docutils literal notranslate"><span class="pre">''</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">date(Boolean)</span></code></div>
<div class="line">print current date and time (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is
<code class="docutils literal notranslate"><span class="pre">true</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">versions(Boolean)</span></code></div>
<div class="line">print Logtalk and backend version data (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>;
default is <code class="docutils literal notranslate"><span class="pre">false</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">directory_paths(Boolean)</span></code></div>
<div class="line">print file directory paths (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is
<code class="docutils literal notranslate"><span class="pre">false</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">path_url_prefixes(PathPrefix,</span> <span class="pre">CodeURLPrefix,</span> <span class="pre">DocURLPrefix)</span></code></div>
<div class="line">code and documenting URL prefixes for a path prefix used when
generating cluster, library, file, and entity links (atoms; no
default; can be specified multiple times)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">url_prefixes(CodeURLPrefix,</span> <span class="pre">DocURLPrefix)</span></code></div>
<div class="line">default URL code and documenting URL prefixes used when generating
cluster, library, file, and entity links (atoms; no default)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">omit_path_prefixes(Prefixes)</span></code></div>
<div class="line">omit common path prefixes when printing directory paths and when
constructing URLs (a list of atoms; default is a list with the user
home directory)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">relation_labels(Boolean)</span></code></div>
<div class="line">print entity relation labels (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is
<code class="docutils literal notranslate"><span class="pre">false</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">externals(Boolean)</span></code></div>
<div class="line">print external nodes (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is <code class="docutils literal notranslate"><span class="pre">true</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">node_type_captions(Boolean)</span></code></div>
<div class="line">print node type captions (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is
<code class="docutils literal notranslate"><span class="pre">false</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">output_directory(Directory)</span></code></div>
<div class="line">directory for the <code class="docutils literal notranslate"><span class="pre">.d2</span></code> and <code class="docutils literal notranslate"><span class="pre">.dot</span></code> files (an atom; default is
<code class="docutils literal notranslate"><span class="pre">'./dot_dias'</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">exclude_directories(Directories)</span></code></div>
<div class="line">list of directories to exclude except as external nodes (default is
<code class="docutils literal notranslate"><span class="pre">[]</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">exclude_files(Files)</span></code></div>
<div class="line">list of source files to exclude except as external nodes (default is
<code class="docutils literal notranslate"><span class="pre">[]</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">exclude_libraries(Libraries)</span></code></div>
<div class="line">list of libraries to exclude except as external nodes (default is
<code class="docutils literal notranslate"><span class="pre">[startup,</span> <span class="pre">scratch_directory]</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">zoom(Boolean)</span></code></div>
<div class="line">generate sub-diagrams and add links and zoom icons to library and
entity nodes (<code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>; default is <code class="docutils literal notranslate"><span class="pre">false</span></code>)</div>
</div>
</li>
<li><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">zoom_url_suffix(Suffix)</span></code></div>
<div class="line">extension for linked diagrams (an atom; default is <code class="docutils literal notranslate"><span class="pre">'.svg'</span></code>)</div>
</div>
</li>
</ul>
<p>When using the <code class="docutils literal notranslate"><span class="pre">zoom(true)</span></code> option, the <code class="docutils literal notranslate"><span class="pre">layout(Layout)</span></code> option
applies only to the top diagram; sub-diagrams will use their own layout
default.</p>
<p>The option <code class="docutils literal notranslate"><span class="pre">omit_path_prefixes(Prefixes)</span></code> with a non-empty list of
prefixes should preferably be used together with the option
<code class="docutils literal notranslate"><span class="pre">directory_paths(true)</span></code> when generating library or file diagrams that
reference external libraries or files. To confirm the exact default
options used by each type of diagram, send the <code class="docutils literal notranslate"><span class="pre">default_options/1</span></code>
message to the diagram object.</p>
<p>Be sure to set the <code class="docutils literal notranslate"><span class="pre">source_data</span></code> flag <code class="docutils literal notranslate"><span class="pre">on</span></code> before compiling the
libraries or files for which you want to generate diagrams.</p>
<p>Support for displaying Prolog modules and Prolog module files in
diagrams of Logtalk applications:</p>
<ul>
<li><div class="line-block">
<div class="line">ECLiPSe</div>
<div class="line">file diagrams don’t display module files</div>
</div>
</li>
<li><div class="line-block">
<div class="line">SICStus Prolog</div>
<div class="line">file diagrams don’t display module files</div>
</div>
</li>
<li><div class="line-block">
<div class="line">SWI-Prolog</div>
<div class="line">full support (uses the SWI-Prolog <code class="docutils literal notranslate"><span class="pre">prolog_xref</span></code> library)</div>
</div>
</li>
<li><div class="line-block">
<div class="line">YAP</div>
<div class="line">full support (uses the YAP <code class="docutils literal notranslate"><span class="pre">prolog_xref</span></code> library)</div>
</div>
</li>
</ul>
</section>
<section id="linking-diagrams">
<h2>Linking diagrams<a class="headerlink" href="#linking-diagrams" title="Link to this heading"></a></h2>
<p>When using SVG output, it’s possible to generate diagrams that link to
other diagrams, to API documentation, to local files and directories,
and to source code repositories.</p>
<p>For generating links between diagrams, use the <code class="docutils literal notranslate"><span class="pre">zoom(true)</span></code> option.
This option allows (1) linking library diagrams to entity diagrams to
predicate cross-referencing diagrams and (2) linking directory diagrams
to file diagrams to entity diagrams to predicate cross-referencing
diagrams. The sub-diagrams are automatically generated. For example,
using the predicates that generate library diagrams will also
automatically generate the entity and predicate cross-referencing
diagrams.</p>
<p>To generate local links for opening directories, files, and file
locations in selected text editors, set the URL code prefix:</p>
<ul class="simple">
<li><p>VSCode: <code class="docutils literal notranslate"><span class="pre">url_prefixes('vscode://file/',</span> <span class="pre">DocPrefix)</span></code></p></li>
<li><p>VSCodium: <code class="docutils literal notranslate"><span class="pre">url_prefixes('vscodium://file/',</span> <span class="pre">DocPrefix)</span></code></p></li>
<li><p>Cursor: <code class="docutils literal notranslate"><span class="pre">url_prefixes('cursor://file/',</span> <span class="pre">DocPrefix)</span></code></p></li>
<li><p>PearAI: <code class="docutils literal notranslate"><span class="pre">url_prefixes('pearai://file/',</span> <span class="pre">DocPrefix)</span></code></p></li>
<li><p>Windsurf: <code class="docutils literal notranslate"><span class="pre">url_prefixes('windsurf://file/',</span> <span class="pre">DocPrefix)</span></code></p></li>
<li><p>Zed: <code class="docutils literal notranslate"><span class="pre">url_prefixes('zed://file/',</span> <span class="pre">DocPrefix)</span></code></p></li>
<li><p>BBEdit: <code class="docutils literal notranslate"><span class="pre">url_prefixes('x-bbedit://open?url=file://',</span> <span class="pre">DocPrefix)</span></code></p></li>
<li><p>MacVim: <code class="docutils literal notranslate"><span class="pre">url_prefixes('mvim://open?url=file://',</span> <span class="pre">DocPrefix)</span></code></p></li>
<li><p>TextMate: <code class="docutils literal notranslate"><span class="pre">url_prefixes('txmt://open?url=file://',</span> <span class="pre">DocPrefix)</span></code></p></li>
<li><p>IDEA: <code class="docutils literal notranslate"><span class="pre">url_prefixes('idea://open?file=',</span> <span class="pre">DocPrefix)</span></code></p></li>
<li><p>PyCharm: <code class="docutils literal notranslate"><span class="pre">url_prefixes('pycharm://open?file=',</span> <span class="pre">DocPrefix)</span></code></p></li>
</ul>
<p>In this case, the <code class="docutils literal notranslate"><span class="pre">DocPrefix</span></code> argument should be the path to the
directory containing the HTML version of the application APIs.</p>
<p>As most of the text editor URL scheme handlers require local links to
use absolute paths, the <code class="docutils literal notranslate"><span class="pre">omit_path_prefixes/1</span></code> option is ignored. Note
that local links require text editor support for URL schemes that can
handle both file and directory links.</p>
<p>To generate links to API documentation and source code repositories, use
the options <code class="docutils literal notranslate"><span class="pre">path_url_prefixes/3</span></code> (or <code class="docutils literal notranslate"><span class="pre">url_prefixes/2</span></code> for simpler
cases) and <code class="docutils literal notranslate"><span class="pre">omit_path_prefixes/1</span></code>. The idea is that the
<code class="docutils literal notranslate"><span class="pre">omit_path_prefixes/1</span></code> option specifies local file prefixes that will
be cut and replaced by the URL prefixes (which can be path prefix
specific when addressing multiple code repositories). To generate local
file system URLs, define the empty atom, <code class="docutils literal notranslate"><span class="pre">''</span></code>, as a prefix. As an
example, consider the Logtalk library. Its source code is available from
a GitHub repository, and its documentation is published on the Logtalk
website. The relevant URLs in this case are:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/LogtalkDotOrg/logtalk3/">https://github.com/LogtalkDotOrg/logtalk3/</a> (source code)</p></li>
<li><p><a class="reference external" href="https://logtalk.org/library/">https://logtalk.org/library/</a> (API documentation)</p></li>
</ul>
<p>Git source code URLs should include the commit SHA1 to ensure that
entity and predicate file line information in the URLs remain valid if
the code changes in later commits. Assuming a <code class="docutils literal notranslate"><span class="pre">GitHub</span></code> variable bound
to the SHA1 commit URL we want to reference, an inheritance diagram can
be generated using the goal:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>| <span class="o">?-</span> <span class="nv">GitHub</span>  <span class="o">=</span> <span class="s">&#39;https://github.com/LogtalkDotOrg/logtalk3/commit/eb156d46e135ac47ef23adcc5d20d49dd8b66abb&#39;</span>,
     <span class="nv">APIDocs</span> <span class="o">=</span> <span class="s">&#39;https://logtalk.org/library/&#39;</span>,
     <span class="k">logtalk_load</span>(diagrams(loader)),
     <span class="k">set_logtalk_flag</span>(source_data, on),
     <span class="k">logtalk_load</span>(library(all_loader)),
     inheritance_diagram<span class="o">::</span>rlibrary(library, [
         title(<span class="s">&#39;Logtalk library&#39;</span>),
         node_type_captions(<span class="k">true</span>),
         zoom(<span class="k">true</span>),
         path_url_prefixes(<span class="s">&#39;$LOGTALKUSER/&#39;</span>, <span class="nv">GitHub</span>, <span class="nv">APIDocs</span>),
         path_url_prefixes(<span class="s">&#39;$LOGTALKHOME/&#39;</span>, <span class="nv">GitHub</span>, <span class="nv">APIDocs</span>),
         omit_path_prefixes([<span class="s">&#39;$LOGTALKUSER/&#39;</span>, <span class="s">&#39;$LOGTALKHOME/&#39;</span>, <span class="s">&#39;$HOME/&#39;</span>])
     ]).
</pre></div>
</div>
<p>The two <code class="docutils literal notranslate"><span class="pre">path_url_prefixes/3</span></code> options take care of source code and API
documentation for entities loaded either from the Logtalk installation
directory (whose location is given by the <code class="docutils literal notranslate"><span class="pre">LOGTALKHOME</span></code> environment
variable) or from the Logtalk user directory (whose location is given by
the <code class="docutils literal notranslate"><span class="pre">LOGTALKUSER</span></code> environment variable). As we also don’t want any
local operating-system paths to be exposed in the diagram, we use the
<code class="docutils literal notranslate"><span class="pre">omit_path_prefixes/1</span></code> option to suppress those path prefixes. Note
that all the paths and URLs must end with a slash for proper handling.
The <code class="docutils literal notranslate"><span class="pre">git</span></code> library may be useful to retrieve the commit SHA1 from a
local repo directory.</p>
<p>For both <code class="docutils literal notranslate"><span class="pre">path_url_prefixes/3</span></code> and <code class="docutils literal notranslate"><span class="pre">omit_path_prefixes/1</span></code> options,
when a path prefix is itself a prefix of another path, the shorter path
must come last to ensure correct links.</p>
<p>See the <code class="docutils literal notranslate"><span class="pre">SCRIPT.txt</span></code> file in the tool directory for additional
examples. To avoid retyping such complex goals when updating diagrams,
use the <code class="docutils literal notranslate"><span class="pre">doclet</span></code> tool to save and reapply them easily (e.g., by using
the <code class="docutils literal notranslate"><span class="pre">make</span></code> tool with the <code class="docutils literal notranslate"><span class="pre">documentation</span></code> target).</p>
</section>
<section id="creating-diagrams-for-prolog-module-applications">
<h2>Creating diagrams for Prolog module applications<a class="headerlink" href="#creating-diagrams-for-prolog-module-applications" title="Link to this heading"></a></h2>
<p>Currently limited to SWI-Prolog and YAP Prolog module applications due
to the lack of a comprehensive reflection API in other Prolog systems.</p>
<p>Simply load your Prolog module application and its dependencies and then
use diagram entity, directory, or file predicates. Library diagram
predicates are not supported. See the <code class="docutils literal notranslate"><span class="pre">SCRIPT.txt</span></code> file in the tool
directory for some usage examples. Note that support for diagrams with
links to API documentation is quite limited, however, due to the lack of
Prolog standards.</p>
</section>
<section id="creating-diagrams-for-plain-prolog-files">
<h2>Creating diagrams for plain Prolog files<a class="headerlink" href="#creating-diagrams-for-plain-prolog-files" title="Link to this heading"></a></h2>
<p>This tool can also be used to create predicate cross-referencing
diagrams for plain Prolog files. For example, if the Prolog file is
named <code class="docutils literal notranslate"><span class="pre">code.pl</span></code>, simply define an object including its code:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(code).
<span class="p">    :- </span><span class="k">include</span>(<span class="s">&#39;code.pl&#39;</span>).
<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>Save the object to an e.g. <code class="docutils literal notranslate"><span class="pre">code.lgt</span></code> file in the same directory as
the Prolog file and then load it and create the diagram:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>| <span class="o">?-</span> <span class="k">logtalk_load</span>(code),
     xref_diagram<span class="o">::</span>entity(code).
</pre></div>
</div>
<p>An alternative is to use the <code class="docutils literal notranslate"><span class="pre">object_wrapper_hook</span></code> provided by the
<code class="docutils literal notranslate"><span class="pre">hook_objects</span></code> library:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>| <span class="o">?-</span> <span class="k">logtalk_load</span>(hook_objects(loader)).
...

| <span class="o">?-</span> <span class="k">logtalk_load</span>(code, [hook(object_wrapper_hook)]),
     xref_diagram<span class="o">::</span>entity(code).
</pre></div>
</div>
</section>
<section id="other-notes">
<h2>Other notes<a class="headerlink" href="#other-notes" title="Link to this heading"></a></h2>
<p>Generating complete diagrams requires that all referenced entities are
loaded. When that is not the case, notably when generating
cross-referencing diagrams, missing entities can result in incomplete
diagrams.</p>
<p>For complex applications, diagrams can often be made simpler and more
readable by omitting external nodes (see the <code class="docutils literal notranslate"><span class="pre">externals/1</span></code> option)
and/or using one of the alternatives to <code class="docutils literal notranslate"><span class="pre">dot</span></code> provided by Graphviz
depending on the type of the diagram (see the section above on supported
graph languages for more details).</p>
<p>When generating entity predicate call cross-reference diagrams, caller
nodes are not created for auxiliary predicates. For example, if the
<code class="docutils literal notranslate"><span class="pre">meta_compiler</span></code> library is used to optimize meta-predicate calls, the
diagrams may show predicates that are not apparently called by any other
predicate when the callers are from the optimized meta-predicate goals
(which are called via library generated auxiliary predicates). A
workaround in this case would be creating a dedicated loader file that
doesn’t load (and apply) the <code class="docutils literal notranslate"><span class="pre">meta_compiler</span></code> library when generating
the diagrams.</p>
<p>When generating diagrams in SVG format, a copy of the <code class="docutils literal notranslate"><span class="pre">diagrams.css</span></code>
file must exist in any directory used for publishing diagrams using it.
The <code class="docutils literal notranslate"><span class="pre">lgt2svg</span></code> scripts also take care of copying this file.</p>
<p>The Graphviz command-line utilities, e.g., <code class="docutils literal notranslate"><span class="pre">dot</span></code>, are notorious for
random crashes (segmentation faults usually), often requiring retrying
conversions from <code class="docutils literal notranslate"><span class="pre">.dot</span></code> files to other formats. A possible workaround
is to repeat the command until it completes without error. See, for
example, the <code class="docutils literal notranslate"><span class="pre">lgt2svg.sh</span></code> script.</p>
<p>The conversion by the <code class="docutils literal notranslate"><span class="pre">d2</span></code> command-line executable of <code class="docutils literal notranslate"><span class="pre">.d2</span></code> files to
<code class="docutils literal notranslate"><span class="pre">.svg</span></code> files can be quite slow (as of its 0.6.8 version) with the
default <code class="docutils literal notranslate"><span class="pre">elk</span></code> layout engine. The <code class="docutils literal notranslate"><span class="pre">dagre</span></code> layout engine is much
faster but doesn’t support a node referencing itself (notably, a node
representing a metaclass that instantiates itself).</p>
<p>Using the default d2 layout engine (<code class="docutils literal notranslate"><span class="pre">elk</span></code>) works fine with graphs with
a relatively small number of nodes and edges. When that’s not the case,
it’s a good idea to experiment with other layout engines.</p>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="debugger.html" class="btn btn-neutral float-left" title="debugger" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="doclet.html" class="btn btn-neutral float-right" title="doclet" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 1998-2025, Paulo Moura.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>